home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 24 / AACD 24.iso / AACD / Programming / gcc-2.95.3-3 / info / g77.info-13 < prev    next >
Encoding:
GNU Info File  |  2001-07-15  |  50.4 KB  |  1,236 lines
  1. This is Info file f/g77.info, produced by Makeinfo version 1.68 from
  2. the input file ./f/g77.texi.
  3.  
  4. INFO-DIR-SECTION Programming
  5. START-INFO-DIR-ENTRY
  6. * g77: (g77).                  The GNU Fortran compiler.
  7. END-INFO-DIR-ENTRY
  8.    This file documents the use and the internals of the GNU Fortran
  9. (`g77') compiler.  It corresponds to the GCC-2.95 version of `g77'.
  10.  
  11.    Published by the Free Software Foundation 59 Temple Place - Suite 330
  12. Boston, MA 02111-1307 USA
  13.  
  14.    Copyright (C) 1995-1999 Free Software Foundation, Inc.
  15.  
  16.    Permission is granted to make and distribute verbatim copies of this
  17. manual provided the copyright notice and this permission notice are
  18. preserved on all copies.
  19.  
  20.    Permission is granted to copy and distribute modified versions of
  21. this manual under the conditions for verbatim copying, provided also
  22. that the sections entitled "GNU General Public License," "Funding for
  23. Free Software," and "Protect Your Freedom--Fight `Look And Feel'" are
  24. included exactly as in the original, and provided that the entire
  25. resulting derived work is distributed under the terms of a permission
  26. notice identical to this one.
  27.  
  28.    Permission is granted to copy and distribute translations of this
  29. manual into another language, under the above conditions for modified
  30. versions, except that the sections entitled "GNU General Public
  31. License," "Funding for Free Software," and "Protect Your Freedom--Fight
  32. `Look And Feel'", and this permission notice, may be included in
  33. translations approved by the Free Software Foundation instead of in the
  34. original English.
  35.  
  36.    Contributed by James Craig Burley (<craig@jcb-sc.com>).  Inspired by
  37. a first pass at translating `g77-0.5.16/f/DOC' that was contributed to
  38. Craig by David Ronis (<ronis@onsager.chem.mcgill.ca>).
  39.  
  40. 
  41. File: g77.info,  Node: Time Intrinsic (VXT),  Next: UMask Intrinsic (function),  Prev: TanD Intrinsic,  Up: Other Intrinsics
  42.  
  43. Time Intrinsic (VXT)
  44. ....................
  45.  
  46.      CALL Time(TIME)
  47.  
  48. TIME: `CHARACTER*8'; scalar; INTENT(OUT).
  49.  
  50. Intrinsic groups: `vxt'.
  51.  
  52. Description:
  53.  
  54.    Returns in TIME a character representation of the current time as
  55. obtained from `ctime(3)'.
  56.  
  57.    Programs making use of this intrinsic might not be Year 10000 (Y10K)
  58. compliant.  For example, the date might appear, to such programs, to
  59. wrap around (change from a larger value to a smaller one) as of the
  60. Year 10000.
  61.  
  62.    *Note FDate Intrinsic (subroutine)::, for an equivalent routine.
  63.  
  64.    For information on other intrinsics with the same name: *Note Time
  65. Intrinsic (UNIX)::.
  66.  
  67. 
  68. File: g77.info,  Node: UMask Intrinsic (function),  Next: Unlink Intrinsic (function),  Prev: Time Intrinsic (VXT),  Up: Other Intrinsics
  69.  
  70. UMask Intrinsic (function)
  71. ..........................
  72.  
  73.      UMask(MASK)
  74.  
  75. UMask: `INTEGER(KIND=1)' function.
  76.  
  77. MASK: `INTEGER'; scalar; INTENT(IN).
  78.  
  79. Intrinsic groups: `badu77'.
  80.  
  81. Description:
  82.  
  83.    Sets the file creation mask to MASK and returns the old value.  See
  84. `umask(2)'.
  85.  
  86.    Due to the side effects performed by this intrinsic, the function
  87. form is not recommended.
  88.  
  89.    For information on other intrinsics with the same name: *Note UMask
  90. Intrinsic (subroutine)::.
  91.  
  92. 
  93. File: g77.info,  Node: Unlink Intrinsic (function),  Next: ZExt Intrinsic,  Prev: UMask Intrinsic (function),  Up: Other Intrinsics
  94.  
  95. Unlink Intrinsic (function)
  96. ...........................
  97.  
  98.      Unlink(FILE)
  99.  
  100. Unlink: `INTEGER(KIND=1)' function.
  101.  
  102. FILE: `CHARACTER'; scalar; INTENT(IN).
  103.  
  104. Intrinsic groups: `badu77'.
  105.  
  106. Description:
  107.  
  108.    Unlink the file FILE.  A null character (`CHAR(0)') marks the end of
  109. the name in FILE--otherwise, trailing blanks in FILE are ignored.
  110. Returns 0 on success or a non-zero error code.  See `unlink(2)'.
  111.  
  112.    Due to the side effects performed by this intrinsic, the function
  113. form is not recommended.
  114.  
  115.    For information on other intrinsics with the same name: *Note Unlink
  116. Intrinsic (subroutine)::.
  117.  
  118. 
  119. File: g77.info,  Node: ZExt Intrinsic,  Prev: Unlink Intrinsic (function),  Up: Other Intrinsics
  120.  
  121. ZExt Intrinsic
  122. ..............
  123.  
  124.    This intrinsic is not yet implemented.  The name is, however,
  125. reserved as an intrinsic.  Use `EXTERNAL ZExt' to use this name for an
  126. external procedure.
  127.  
  128. 
  129. File: g77.info,  Node: Other Compilers,  Next: Other Languages,  Prev: Other Dialects,  Up: Top
  130.  
  131. Other Compilers
  132. ***************
  133.  
  134.    An individual Fortran source file can be compiled to an object
  135. (`*.o') file instead of to the final program executable.  This allows
  136. several portions of a program to be compiled at different times and
  137. linked together whenever a new version of the program is needed.
  138. However, it introduces the issue of "object compatibility" across the
  139. various object files (and libraries, or `*.a' files) that are linked
  140. together to produce any particular executable file.
  141.  
  142.    Object compatibility is an issue when combining, in one program,
  143. Fortran code compiled by more than one compiler (or more than one
  144. configuration of a compiler).  If the compilers disagree on how to
  145. transform the names of procedures, there will normally be errors when
  146. linking such programs.  Worse, if the compilers agree on naming, but
  147. disagree on issues like how to pass parameters, return arguments, and
  148. lay out `COMMON' areas, the earliest detected errors might be the
  149. incorrect results produced by the program (and that assumes these
  150. errors are detected, which is not always the case).
  151.  
  152.    Normally, `g77' generates code that is object-compatible with code
  153. generated by a version of `f2c' configured (with, for example, `f2c.h'
  154. definitions) to be generally compatible with `g77' as built by `gcc'.
  155. (Normally, `f2c' will, by default, conform to the appropriate
  156. configuration, but it is possible that older or perhaps even newer
  157. versions of `f2c', or versions having certain configuration changes to
  158. `f2c' internals, will produce object files that are incompatible with
  159. `g77'.)
  160.  
  161.    For example, a Fortran string subroutine argument will become two
  162. arguments on the C side: a `char *' and an `int' length.
  163.  
  164.    Much of this compatibility results from the fact that `g77' uses the
  165. same run-time library, `libf2c', used by `f2c', though `g77' gives its
  166. version the name `libg2c' so as to avoid conflicts when linking,
  167. installing them in the same directories, and so on.
  168.  
  169.    Other compilers might or might not generate code that is
  170. object-compatible with `libg2c' and current `g77', and some might offer
  171. such compatibility only when explicitly selected via a command-line
  172. option to the compiler.
  173.  
  174.    *Note: This portion of the documentation definitely needs a lot of
  175. work!*
  176.  
  177. * Menu:
  178.  
  179. * Dropping f2c Compatibility::  When speed is more important.
  180. * Compilers Other Than f2c::    Interoperation with code from other compilers.
  181.  
  182. 
  183. File: g77.info,  Node: Dropping f2c Compatibility,  Next: Compilers Other Than f2c,  Up: Other Compilers
  184.  
  185. Dropping `f2c' Compatibility
  186. ============================
  187.  
  188.    Specifying `-fno-f2c' allows `g77' to generate, in some cases,
  189. faster code, by not needing to allow to the possibility of linking with
  190. code compiled by `f2c'.
  191.  
  192.    For example, this affects how `REAL(KIND=1)', `COMPLEX(KIND=1)', and
  193. `COMPLEX(KIND=2)' functions are called.  With `-fno-f2c', they are
  194. compiled as returning the appropriate `gcc' type (`float', `__complex__
  195. float', `__complex__ double', in many configurations).
  196.  
  197.    With `-ff2c' in force, they are compiled differently (with perhaps
  198. slower run-time performance) to accommodate the restrictions inherent
  199. in `f2c''s use of K&R C as an intermediate language--`REAL(KIND=1)'
  200. functions return C's `double' type, while `COMPLEX' functions return
  201. `void' and use an extra argument pointing to a place for the functions
  202. to return their values.
  203.  
  204.    It is possible that, in some cases, leaving `-ff2c' in force might
  205. produce faster code than using `-fno-f2c'.  Feel free to experiment,
  206. but remember to experiment with changing the way *entire programs and
  207. their Fortran libraries are compiled* at a time, since this sort of
  208. experimentation affects the interface of code generated for a Fortran
  209. source file--that is, it affects object compatibility.
  210.  
  211.    Note that `f2c' compatibility is a fairly static target to achieve,
  212. though not necessarily perfectly so, since, like `g77', it is still
  213. being improved.  However, specifying `-fno-f2c' causes `g77' to
  214. generate code that will probably be incompatible with code generated by
  215. future versions of `g77' when the same option is in force.  You should
  216. make sure you are always able to recompile complete programs from
  217. source code when upgrading to new versions of `g77' or `f2c',
  218. especially when using options such as `-fno-f2c'.
  219.  
  220.    Therefore, if you are using `g77' to compile libraries and other
  221. object files for possible future use and you don't want to require
  222. recompilation for future use with subsequent versions of `g77', you
  223. might want to stick with `f2c' compatibility for now, and carefully
  224. watch for any announcements about changes to the `f2c'/`libf2c'
  225. interface that might affect existing programs (thus requiring
  226. recompilation).
  227.  
  228.    It is probable that a future version of `g77' will not, by default,
  229. generate object files compatible with `f2c', and that version probably
  230. would no longer use `libf2c'.  If you expect to depend on this
  231. compatibility in the long term, use the options `-ff2c -ff2c-library'
  232. when compiling all of the applicable code.  This should cause future
  233. versions of `g77' either to produce compatible code (at the expense of
  234. the availability of some features and performance), or at the very
  235. least, to produce diagnostics.
  236.  
  237.    (The library `g77' produces will no longer be named `libg2c' when it
  238. is no longer generally compatible with `libf2c'.  It will likely be
  239. referred to, and, if installed as a distinct library, named `libg77',
  240. or some other as-yet-unused name.)
  241.  
  242. 
  243. File: g77.info,  Node: Compilers Other Than f2c,  Prev: Dropping f2c Compatibility,  Up: Other Compilers
  244.  
  245. Compilers Other Than `f2c'
  246. ==========================
  247.  
  248.    On systems with Fortran compilers other than `f2c' and `g77', code
  249. compiled by `g77' is not expected to work well with code compiled by
  250. the native compiler.  (This is true for `f2c'-compiled objects as well.)
  251. Libraries compiled with the native compiler probably will have to be
  252. recompiled with `g77' to be used with `g77'-compiled code.
  253.  
  254.    Reasons for such incompatibilities include:
  255.  
  256.    * There might be differences in the way names of Fortran procedures
  257.      are translated for use in the system's object-file format.  For
  258.      example, the statement `CALL FOO' might be compiled by `g77' to
  259.      call a procedure the linker `ld' sees given the name `_foo_',
  260.      while the apparently corresponding statement `SUBROUTINE FOO'
  261.      might be compiled by the native compiler to define the
  262.      linker-visible name `_foo', or `_FOO_', and so on.
  263.  
  264.    * There might be subtle type mismatches which cause subroutine
  265.      arguments and function return values to get corrupted.
  266.  
  267.      This is why simply getting `g77' to transform procedure names the
  268.      same way a native compiler does is not usually a good idea--unless
  269.      some effort has been made to ensure that, aside from the way the
  270.      two compilers transform procedure names, everything else about the
  271.      way they generate code for procedure interfaces is identical.
  272.  
  273.    * Native compilers use libraries of private I/O routines which will
  274.      not be available at link time unless you have the native
  275.      compiler--and you would have to explicitly ask for them.
  276.  
  277.      For example, on the Sun you would have to add `-L/usr/lang/SCx.x
  278.      -lF77 -lV77' to the link command.
  279.  
  280. 
  281. File: g77.info,  Node: Other Languages,  Next: Installation,  Prev: Other Compilers,  Up: Top
  282.  
  283. Other Languages
  284. ***************
  285.  
  286.    *Note: This portion of the documentation definitely needs a lot of
  287. work!*
  288.  
  289. * Menu:
  290.  
  291. * Interoperating with C and C++::
  292.  
  293. 
  294. File: g77.info,  Node: Interoperating with C and C++,  Up: Other Languages
  295.  
  296. Tools and advice for interoperating with C and C++
  297. ==================================================
  298.  
  299.    The following discussion assumes that you are running `g77' in `f2c'
  300. compatibility mode, i.e. not using `-fno-f2c'.  It provides some advice
  301. about quick and simple techniques for linking Fortran and C (or C++),
  302. the most common requirement.  For the full story consult the
  303. description of code generation.  *Note Debugging and Interfacing::.
  304.  
  305.    When linking Fortran and C, it's usually best to use `g77' to do the
  306. linking so that the correct libraries are included (including the maths
  307. one).  If you're linking with C++ you will want to add `-lstdc++',
  308. `-lg++' or whatever.  If you need to use another driver program (or
  309. `ld' directly), you can find out what linkage options `g77' passes by
  310. running `g77 -v'.
  311.  
  312. * Menu:
  313.  
  314. * C Interfacing Tools::
  315. * C Access to Type Information::
  316. * f2c Skeletons and Prototypes::
  317. * C++ Considerations::
  318. * Startup Code::
  319.  
  320. 
  321. File: g77.info,  Node: C Interfacing Tools,  Next: C Access to Type Information,  Up: Interoperating with C and C++
  322.  
  323. C Interfacing Tools
  324. -------------------
  325.  
  326.    Even if you don't actually use it as a compiler, `f2c' from
  327. `ftp://ftp.netlib.org/f2c/src', can be a useful tool when you're
  328. interfacing (linking) Fortran and C.  *Note Generating Skeletons and
  329. Prototypes with `f2c': f2c Skeletons and Prototypes.
  330.  
  331.    To use `f2c' for this purpose you only need retrieve and build the
  332. `src' directory from the distribution, consult the `README'
  333. instructions there for machine-specifics, and install the `f2c' program
  334. on your path.
  335.  
  336.    Something else that might be useful is `cfortran.h' from
  337. `ftp://zebra/desy.de/cfortran'.  This is a fairly general tool which
  338. can be used to generate interfaces for calling in both directions
  339. between Fortran and C.  It can be used in `f2c' mode with
  340. `g77'--consult its documentation for details.
  341.  
  342. 
  343. File: g77.info,  Node: C Access to Type Information,  Next: f2c Skeletons and Prototypes,  Prev: C Interfacing Tools,  Up: Interoperating with C and C++
  344.  
  345. Accessing Type Information in C
  346. -------------------------------
  347.  
  348.    Generally, C code written to link with `g77' code--calling and/or
  349. being called from Fortran--should `#include <g2c.h>' to define the C
  350. versions of the Fortran types.  Don't assume Fortran `INTEGER' types
  351. correspond to C `int's, for instance; instead, declare them as
  352. `integer', a type defined by `g2c.h'.  `g2c.h' is installed where `gcc'
  353. will find it by default, assuming you use a copy of `gcc' compatible
  354. with `g77', probably built at the same time as `g77'.
  355.  
  356. 
  357. File: g77.info,  Node: f2c Skeletons and Prototypes,  Next: C++ Considerations,  Prev: C Access to Type Information,  Up: Interoperating with C and C++
  358.  
  359. Generating Skeletons and Prototypes with `f2c'
  360. ----------------------------------------------
  361.  
  362.    A simple and foolproof way to write `g77'-callable C routines--e.g.
  363. to interface with an existing library--is to write a file (named, for
  364. example, `fred.f') of dummy Fortran skeletons comprising just the
  365. declaration of the routine(s) and dummy arguments plus `END' statements.
  366. Then run `f2c' on file `fred.f' to produce `fred.c' into which you can
  367. edit useful code, confident the calling sequence is correct, at least.
  368. (There are some errors otherwise commonly made in generating C
  369. interfaces with `f2c' conventions, such as not using `doublereal' as
  370. the return type of a `REAL' `FUNCTION'.)
  371.  
  372.    `f2c' also can help with calling Fortran from C, using its `-P'
  373. option to generate C prototypes appropriate for calling the Fortran.(1)
  374. If the Fortran code containing any routines to be called from C is in
  375. file `joe.f', use the command `f2c -P joe.f' to generate the file
  376. `joe.P' containing prototype information.  `#include' this in the C
  377. which has to call the Fortran routines to make sure you get it right.
  378.  
  379.    *Note Arrays (DIMENSION): Arrays, for information on the differences
  380. between the way Fortran (including compilers like `g77') and C handle
  381. arrays.
  382.  
  383.    ---------- Footnotes ----------
  384.  
  385.    (1) The files generated like this can also be used for inter-unit
  386. consistency checking of dummy and actual arguments, although the
  387. `ftnchek' tool from `ftp://ftp.netlib.org/fortran' or
  388. `ftp://ftp.dsm.fordham.edu' is probably better for this purpose.
  389.  
  390. 
  391. File: g77.info,  Node: C++ Considerations,  Next: Startup Code,  Prev: f2c Skeletons and Prototypes,  Up: Interoperating with C and C++
  392.  
  393. C++ Considerations
  394. ------------------
  395.  
  396.    `f2c' can be used to generate suitable code for compilation with a
  397. C++ system using the `-C++' option.  The important thing about linking
  398. `g77'-compiled code with C++ is that the prototypes for the `g77'
  399. routines must specify C linkage to avoid name mangling.  So, use an
  400. `extern "C"' declaration.  `f2c''s `-C++' option will take care of this
  401. when generating skeletons or prototype files as above, and also avoid
  402. clashes with C++ reserved words in addition to those in C.
  403.  
  404. 
  405. File: g77.info,  Node: Startup Code,  Prev: C++ Considerations,  Up: Interoperating with C and C++
  406.  
  407. Startup Code
  408. ------------
  409.  
  410.    Unlike with some runtime systems, it shouldn't be necessary (unless
  411. there are bugs) to use a Fortran main program unit to ensure the
  412. runtime--specifically the I/O system--is initialized.
  413.  
  414.    However, to use the `g77' intrinsics `GETARG' and `IARGC', either
  415. the `main' routine from the `libg2c' library must be used, or the
  416. `f_setarg' routine (new as of `egcs' version 1.1 and `g77' version
  417. 0.5.23) must be called with the appropriate `argc' and `argv' arguments
  418. prior to the program calling `GETARG' or `IARGC'.
  419.  
  420.    To provide more flexibility for mixed-language programming involving
  421. `g77' while allowing for shared libraries, as of `egcs' version 1.1 and
  422. `g77' version 0.5.23, `g77''s `main' routine in `libg2c' does the
  423. following, in order:
  424.  
  425.   1. Calls `f_setarg' with the incoming `argc' and `argv' arguments, in
  426.      the same order as for `main' itself.
  427.  
  428.      This sets up the command-line environment for `GETARG' and `IARGC'.
  429.  
  430.   2. Calls `f_setsig' (with no arguments).
  431.  
  432.      This sets up the signaling and exception environment.
  433.  
  434.   3. Calls `f_init' (with no arguments).
  435.  
  436.      This initializes the I/O environment, though that should not be
  437.      necessary, as all I/O functions in `libf2c' are believed to call
  438.      `f_init' automatically, if necessary.
  439.  
  440.      (A future version of `g77' might skip this explicit step, to speed
  441.      up normal exit of a program.)
  442.  
  443.   4. Arranges for `f_exit' to be called (with no arguments) when the
  444.      program exits.
  445.  
  446.      This ensures that the I/O environment is properly shut down before
  447.      the program exits normally.  Otherwise, output buffers might not
  448.      be fully flushed, scratch files might not be deleted, and so on.
  449.  
  450.      The simple way `main' does this is to call `f_exit' itself after
  451.      calling `MAIN__' (in the next step).
  452.  
  453.      However, this does not catch the cases where the program might
  454.      call `exit' directly, instead of using the `EXIT' intrinsic
  455.      (implemented as `exit_' in `libf2c').
  456.  
  457.      So, `main' attempts to use the operating environment's `onexit' or
  458.      `atexit' facility, if available, to cause `f_exit' to be called
  459.      automatically upon any invocation of `exit'.
  460.  
  461.   5. Calls `MAIN__' (with no arguments).
  462.  
  463.      This starts executing the Fortran main program unit for the
  464.      application.  (Both `g77' and `f2c' currently compile a main
  465.      program unit so that its global name is `MAIN__'.)
  466.  
  467.   6. If no `onexit' or `atexit' is provided by the system, calls
  468.      `f_exit'.
  469.  
  470.   7. Calls `exit' with a zero argument, to signal a successful program
  471.      termination.
  472.  
  473.   8. Returns a zero value to the caller, to signal a successful program
  474.      termination, in case `exit' doesn't exit on the system.
  475.  
  476.    All of the above names are C `extern' names, i.e. not mangled.
  477.  
  478.    When using the `main' procedure provided by `g77' without a Fortran
  479. main program unit, you need to provide `MAIN__' as the entry point for
  480. your C code.  (Make sure you link the object file that defines that
  481. entry point with the rest of your program.)
  482.  
  483.    To provide your own `main' procedure in place of `g77''s, make sure
  484. you specify the object file defining that procedure *before* `-lg2c' on
  485. the `g77' command line.  Since the `-lg2c' option is implicitly
  486. provided, this is usually straightforward.  (Use the `--verbose' option
  487. to see how and where `g77' implicitly adds `-lg2c' in a command line
  488. that will link the program.  Feel free to specify `-lg2c' explicitly,
  489. as appropriate.)
  490.  
  491.    However, when providing your own `main', make sure you perform the
  492. appropriate tasks in the appropriate order.  For example, if your
  493. `main' does not call `f_setarg', make sure the rest of your application
  494. does not call `GETARG' or `IARGC'.
  495.  
  496.    And, if your `main' fails to ensure that `f_exit' is called upon
  497. program exit, some files might end up incompletely written, some
  498. scratch files might be left lying around, and some existing files being
  499. written might be left with old data not properly truncated at the end.
  500.  
  501.    Note that, generally, the `g77' operating environment does not
  502. depend on a procedure named `MAIN__' actually being called prior to any
  503. other `g77'-compiled code.  That is, `MAIN__' does not, itself, set up
  504. any important operating-environment characteristics upon which other
  505. code might depend.  This might change in future versions of `g77', with
  506. appropriate notification in the release notes.
  507.  
  508.    For more information, consult the source code for the above routines.
  509. These are in `egcs/libf2c/libF77/', named `main.c', `setarg.c',
  510. `setsig.c', `getarg_.c', and `iargc_.c'.
  511.  
  512.    Also, the file `egcs/gcc/f/com.c' contains the code `g77' uses to
  513. open-code (inline) references to `IARGC'.
  514.  
  515. 
  516. File: g77.info,  Node: Installation,  Next: Debugging and Interfacing,  Prev: Other Languages,  Up: Top
  517.  
  518. Installing GNU Fortran
  519. **********************
  520.  
  521.    The following information describes how to install `g77'.
  522.  
  523.    Note that, for users of the GCC-2.95 version of `g77', much of the
  524. information is obsolete, and is superceded by the GCC installation
  525. procedures.  Such information is accordingly omitted and flagged as
  526. such.
  527.  
  528.    The following information was last updated on 1999-07-17:
  529.  
  530. * Menu:
  531.  
  532. * Prerequisites::          Make sure your system is ready for `g77'.
  533. * Problems Installing::    Known trouble areas.
  534. * Settings::               Changing `g77' internals before building.
  535. * Quick Start::            The easier procedure for non-experts.
  536. * Complete Installation::  For experts, or those who want to be: the details.
  537. * Distributing Binaries::  If you plan on distributing your `g77'.
  538.  
  539. 
  540. File: g77.info,  Node: Prerequisites,  Next: Problems Installing,  Up: Installation
  541.  
  542. Prerequisites
  543. =============
  544.  
  545.    For users of the GCC-2.95 version of `g77', this information is
  546. superceded by the GCC installation instructions.
  547.  
  548. 
  549. File: g77.info,  Node: Problems Installing,  Next: Settings,  Prev: Prerequisites,  Up: Installation
  550.  
  551. Problems Installing
  552. ===================
  553.  
  554.    This is a list of problems (and some apparent problems which don't
  555. really mean anything is wrong) that show up when configuring, building,
  556. installing, or porting GNU Fortran.
  557.  
  558.    *Note Installation Problems: (gcc)Installation Problems, for more
  559. information on installation problems that can afflict either `gcc' or
  560. `g77'.
  561.  
  562. * Menu:
  563.  
  564. * General Problems::         Problems afflicting most or all systems.
  565. * System-specific Problems:: Problems afflicting particular systems.
  566. * Cross-compiler Problems::  Problems afflicting cross-compilation setups.
  567.  
  568. 
  569. File: g77.info,  Node: General Problems,  Next: System-specific Problems,  Up: Problems Installing
  570.  
  571. General Problems
  572. ----------------
  573.  
  574.    These problems can occur on most or all systems.
  575.  
  576. * Menu:
  577.  
  578. * GNU C Required::             Why even ANSI C is not enough.
  579. * Patching GNU CC::            Why `gcc' needn't be patched.
  580. * Building GNU CC Necessary::  Why you can't build *just* Fortran.
  581. * Missing strtoul or bsearch:: When linking `f771' fails.
  582. * Cleanup Kills Stage Directories::  For `g77' developers.
  583. * LANGUAGES Macro Ignored::    Sometimes `LANGUAGES' is ignored.
  584.  
  585. 
  586. File: g77.info,  Node: GNU C Required,  Next: Patching GNU CC,  Up: General Problems
  587.  
  588. GNU C Required
  589. ..............
  590.  
  591.    Compiling `g77' requires GNU C, not just ANSI C.  Fixing this
  592. wouldn't be very hard (just tedious), but the code using GNU extensions
  593. to the C language is expected to be rewritten for 0.6 anyway, so there
  594. are no plans for an interim fix.
  595.  
  596.    This requirement does not mean you must already have `gcc' installed
  597. to build `g77'.  As long as you have a working C compiler, you can use a
  598. "bootstrap" build to automate the process of first building `gcc' using
  599. the working C compiler you have, then building `g77' and rebuilding
  600. `gcc' using that just-built `gcc', and so on.
  601.  
  602. 
  603. File: g77.info,  Node: Patching GNU CC,  Next: Building GNU CC Necessary,  Prev: GNU C Required,  Up: General Problems
  604.  
  605. Patching GNU CC
  606. ...............
  607.  
  608.    `g77' no longer requires application of a patch file to the `gcc'
  609. compiler tree.  In fact, no such patch file is distributed with `g77'.
  610. This is as of version 0.5.23 and `egcs' version 1.0.
  611.  
  612. 
  613. File: g77.info,  Node: Building GNU CC Necessary,  Next: Missing strtoul or bsearch,  Prev: Patching GNU CC,  Up: General Problems
  614.  
  615. Building GNU CC Necessary
  616. .........................
  617.  
  618.    It should be possible to build the runtime without building `cc1'
  619. and other non-Fortran items, but, for now, an easy way to do that is
  620. not yet established.
  621.  
  622. 
  623. File: g77.info,  Node: Missing strtoul or bsearch,  Next: Cleanup Kills Stage Directories,  Prev: Building GNU CC Necessary,  Up: General Problems
  624.  
  625. Missing strtoul or bsearch
  626. ..........................
  627.  
  628.    This information does not apply to the GCC-2.95 version of `g77',
  629.  
  630. 
  631. File: g77.info,  Node: Cleanup Kills Stage Directories,  Next: LANGUAGES Macro Ignored,  Prev: Missing strtoul or bsearch,  Up: General Problems
  632.  
  633. Cleanup Kills Stage Directories
  634. ...............................
  635.  
  636.    It'd be helpful if `g77''s `Makefile.in' or `Make-lang.in' would
  637. create the various `stageN' directories and their subdirectories, so
  638. developers and expert installers wouldn't have to reconfigure after
  639. cleaning up.
  640.  
  641.    That help has arrived as of version 0.5.23 of `g77' and version 1.1
  642. of `egcs'.  Configuration itself no longer creates any particular
  643. directories that are unique to `g77'.  The build procedures in
  644. `Make-lang.in' take care of that, on demand.
  645.  
  646. 
  647. File: g77.info,  Node: LANGUAGES Macro Ignored,  Prev: Cleanup Kills Stage Directories,  Up: General Problems
  648.  
  649. LANGUAGES Macro Ignored
  650. .......................
  651.  
  652.    Prior to version 0.5.23 of `g77' and version 1.1 of `egcs', `g77'
  653. would sometimes ignore the absence of `f77' and `F77' in the
  654. `LANGUAGES' macro definition used for the `make' command being
  655. processed.
  656.  
  657.    As of `g77' version 0.5.23 and `egcs' version 1.1, `g77' now obeys
  658. this macro in all relevant situations.
  659.  
  660.    However, in versions of `gcc' through 2.8.1, non-`g77' portions of
  661. `gcc', such as `g++', are known to go ahead and perform various
  662. language-specific activities when their respective language strings do
  663. not appear in the `LANGUAGES' macro in effect during that invocation of
  664. `make'.
  665.  
  666.    It is expected that these remaining problems will be fixed in a
  667. future version of `gcc'.
  668.  
  669. 
  670. File: g77.info,  Node: System-specific Problems,  Next: Cross-compiler Problems,  Prev: General Problems,  Up: Problems Installing
  671.  
  672. System-specific Problems
  673. ------------------------
  674.  
  675.    A linker bug on some versions of AIX 4.1 might prevent building when
  676. `g77' is built within `gcc'.  It might also occur when building within
  677. `egcs'.  *Note LINKFAIL::.
  678.  
  679. 
  680. File: g77.info,  Node: Cross-compiler Problems,  Prev: System-specific Problems,  Up: Problems Installing
  681.  
  682. Cross-compiler Problems
  683. -----------------------
  684.  
  685.    `g77' has been in alpha testing since September of 1992, and in
  686. public beta testing since February of 1995.  Alpha testing was done by
  687. a small number of people worldwide on a fairly wide variety of
  688. machines, involving self-compilation in most or all cases.  Beta
  689. testing has been done primarily via self-compilation, but in more and
  690. more cases, cross-compilation (and "criss-cross compilation", where a
  691. version of a compiler is built on one machine to run on a second and
  692. generate code that runs on a third) has been tried and has succeeded,
  693. to varying extents.
  694.  
  695.    Generally, `g77' can be ported to any configuration to which `gcc',
  696. `f2c', and `libf2c' can be ported and made to work together, aside from
  697. the known problems described in this manual.  If you want to port `g77'
  698. to a particular configuration, you should first make sure `gcc' and
  699. `libf2c' can be ported to that configuration before focusing on `g77',
  700. because `g77' is so dependent on them.
  701.  
  702.    Even for cases where `gcc' and `libf2c' work, you might run into
  703. problems with cross-compilation on certain machines, for several
  704. reasons.
  705.  
  706.    * There is one known bug (a design bug to be fixed in 0.6) that
  707.      prevents configuration of `g77' as a cross-compiler in some cases,
  708.      though there are assumptions made during configuration that
  709.      probably make doing non-self-hosting builds a hassle, requiring
  710.      manual intervention.
  711.  
  712.    * `gcc' might still have some trouble being configured for certain
  713.      combinations of machines.  For example, it might not know how to
  714.      handle floating-point constants.
  715.  
  716.    * Improvements to the way `libg2c' is built could make building
  717.      `g77' as a cross-compiler easier--for example, passing and using
  718.      `$(LD)' and `$(AR)' in the appropriate ways.  (This is improved in
  719.      the `egcs' version of `g77', especially as of version 1.1.)
  720.  
  721.    * There are still some challenges putting together the right
  722.      run-time libraries (needed by `libg2c') for a target system,
  723.      depending on the systems involved in the configuration.  (This is
  724.      a general problem with cross-compilation, and with `gcc' in
  725.      particular.)
  726.  
  727. 
  728. File: g77.info,  Node: Settings,  Next: Quick Start,  Prev: Problems Installing,  Up: Installation
  729.  
  730. Changing Settings Before Building
  731. =================================
  732.  
  733.    Here are some internal `g77' settings that can be changed by editing
  734. source files in `egcs/gcc/f/' before building.
  735.  
  736.    This information, and perhaps even these settings, represent
  737. stop-gap solutions to problems people doing various ports of `g77' have
  738. encountered.  As such, none of the following information is expected to
  739. be pertinent in future versions of `g77'.
  740.  
  741. * Menu:
  742.  
  743. * Larger File Unit Numbers::     Raising `MXUNIT'.
  744. * Always Flush Output::          Synchronizing write errors.
  745. * Maximum Stackable Size::       Large arrays forced off the stack.
  746. * Floating-point Bit Patterns::  Possible programs building `g77'
  747.                                    as a cross-compiler.
  748. * Large Initialization::         Large arrays with `DATA'
  749.                                    initialization.
  750. * Alpha Problems Fixed::         Problems with 64-bit systems like
  751.                                    Alphas now fixed?
  752.  
  753. 
  754. File: g77.info,  Node: Larger File Unit Numbers,  Next: Always Flush Output,  Up: Settings
  755.  
  756. Larger File Unit Numbers
  757. ------------------------
  758.  
  759.    As distributed, whether as part of `f2c' or `g77', `libf2c' accepts
  760. file unit numbers only in the range 0 through 99.  For example, a
  761. statement such as `WRITE (UNIT=100)' causes a run-time crash in
  762. `libf2c', because the unit number, 100, is out of range.
  763.  
  764.    If you know that Fortran programs at your installation require the
  765. use of unit numbers higher than 99, you can change the value of the
  766. `MXUNIT' macro, which represents the maximum unit number, to an
  767. appropriately higher value.
  768.  
  769.    To do this, edit the file `egcs/libf2c/libI77/fio.h' in your `g77'
  770. source tree, changing the following line:
  771.  
  772.      #define MXUNIT 100
  773.  
  774.    Change the line so that the value of `MXUNIT' is defined to be at
  775. least one *greater* than the maximum unit number used by the Fortran
  776. programs on your system.
  777.  
  778.    (For example, a program that does `WRITE (UNIT=255)' would require
  779. `MXUNIT' set to at least 256 to avoid crashing.)
  780.  
  781.    Then build or rebuild `g77' as appropriate.
  782.  
  783.    *Note:* Changing this macro has *no* effect on other limits your
  784. system might place on the number of files open at the same time.  That
  785. is, the macro might allow a program to do `WRITE (UNIT=100)', but the
  786. library and operating system underlying `libf2c' might disallow it if
  787. many other files have already been opened (via `OPEN' or implicitly via
  788. `READ', `WRITE', and so on).  Information on how to increase these
  789. other limits should be found in your system's documentation.
  790.  
  791. 
  792. File: g77.info,  Node: Always Flush Output,  Next: Maximum Stackable Size,  Prev: Larger File Unit Numbers,  Up: Settings
  793.  
  794. Always Flush Output
  795. -------------------
  796.  
  797.    Some Fortran programs require output (writes) to be flushed to the
  798. operating system (under UNIX, via the `fflush()' library call) so that
  799. errors, such as disk full, are immediately flagged via the relevant
  800. `ERR=' and `IOSTAT=' mechanism, instead of such errors being flagged
  801. later as subsequent writes occur, forcing the previously written data
  802. to disk, or when the file is closed.
  803.  
  804.    Essentially, the difference can be viewed as synchronous error
  805. reporting (immediate flagging of errors during writes) versus
  806. asynchronous, or, more precisely, buffered error reporting (detection
  807. of errors might be delayed).
  808.  
  809.    `libg2c' supports flagging write errors immediately when it is built
  810. with the `ALWAYS_FLUSH' macro defined.  This results in a `libg2c' that
  811. runs slower, sometimes quite a bit slower, under certain
  812. circumstances--for example, accessing files via the networked file
  813. system NFS--but the effect can be more reliable, robust file I/O.
  814.  
  815.    If you know that Fortran programs requiring this level of precision
  816. of error reporting are to be compiled using the version of `g77' you
  817. are building, you might wish to modify the `g77' source tree so that
  818. the version of `libg2c' is built with the `ALWAYS_FLUSH' macro defined,
  819. enabling this behavior.
  820.  
  821.    To do this, find this line in `egcs/libf2c/f2c.h' in your `g77'
  822. source tree:
  823.  
  824.      /* #define ALWAYS_FLUSH */
  825.  
  826.    Remove the leading `/* ', so the line begins with `#define', and the
  827. trailing ` */'.
  828.  
  829.    Then build or rebuild `g77' as appropriate.
  830.  
  831. 
  832. File: g77.info,  Node: Maximum Stackable Size,  Next: Floating-point Bit Patterns,  Prev: Always Flush Output,  Up: Settings
  833.  
  834. Maximum Stackable Size
  835. ----------------------
  836.  
  837.    `g77', on most machines, puts many variables and arrays on the stack
  838. where possible, and can be configured (by changing
  839. `FFECOM_sizeMAXSTACKITEM' in `egcs/gcc/f/com.c') to force smaller-sized
  840. entities into static storage (saving on stack space) or permit
  841. larger-sized entities to be put on the stack (which can improve
  842. run-time performance, as it presents more opportunities for the GBE to
  843. optimize the generated code).
  844.  
  845.    *Note:* Putting more variables and arrays on the stack might cause
  846. problems due to system-dependent limits on stack size.  Also, the value
  847. of `FFECOM_sizeMAXSTACKITEM' has no effect on automatic variables and
  848. arrays.  *Note But-bugs::, for more information.
  849.  
  850. 
  851. File: g77.info,  Node: Floating-point Bit Patterns,  Next: Large Initialization,  Prev: Maximum Stackable Size,  Up: Settings
  852.  
  853. Floating-point Bit Patterns
  854. ---------------------------
  855.  
  856.    The `g77' build will crash if an attempt is made to build it as a
  857. cross-compiler for a target when `g77' cannot reliably determine the
  858. bit pattern of floating-point constants for the target.  Planned
  859. improvements for version 0.6 of `g77' will give it the capabilities it
  860. needs to not have to crash the build but rather generate correct code
  861. for the target.  (Currently, `g77' would generate bad code under such
  862. circumstances if it didn't crash during the build, e.g. when compiling
  863. a source file that does something like `EQUIVALENCE (I,R)' and `DATA
  864. R/9.43578/'.)
  865.  
  866. 
  867. File: g77.info,  Node: Large Initialization,  Next: Alpha Problems Fixed,  Prev: Floating-point Bit Patterns,  Up: Settings
  868.  
  869. Initialization of Large Aggregate Areas
  870. ---------------------------------------
  871.  
  872.    A warning message is issued when `g77' sees code that provides
  873. initial values (e.g. via `DATA') to an aggregate area (`COMMON' or
  874. `EQUIVALENCE', or even a large enough array or `CHARACTER' variable)
  875. that is large enough to increase `g77''s compile time by roughly a
  876. factor of 10.
  877.  
  878.    This size currently is quite small, since `g77' currently has a
  879. known bug requiring too much memory and time to handle such cases.  In
  880. `egcs/gcc/f/data.c', the macro `FFEDATA_sizeTOO_BIG_INIT_' is defined
  881. to the minimum size for the warning to appear.  The size is specified
  882. in storage units, which can be bytes, words, or whatever, on a
  883. case-by-case basis.
  884.  
  885.    After changing this macro definition, you must (of course) rebuild
  886. and reinstall `g77' for the change to take effect.
  887.  
  888.    Note that, as of version 0.5.18, improvements have reduced the scope
  889. of the problem for *sparse* initialization of large arrays, especially
  890. those with large, contiguous uninitialized areas.  However, the warning
  891. is issued at a point prior to when `g77' knows whether the
  892. initialization is sparse, and delaying the warning could mean it is
  893. produced too late to be helpful.
  894.  
  895.    Therefore, the macro definition should not be adjusted to reflect
  896. sparse cases.  Instead, adjust it to generate the warning when densely
  897. initialized arrays begin to cause responses noticeably slower than
  898. linear performance would suggest.
  899.  
  900. 
  901. File: g77.info,  Node: Alpha Problems Fixed,  Prev: Large Initialization,  Up: Settings
  902.  
  903. Alpha Problems Fixed
  904. --------------------
  905.  
  906.    `g77' used to warn when it was used to compile Fortran code for a
  907. target configuration that is not basically a 32-bit machine (such as an
  908. Alpha, which is a 64-bit machine, especially if it has a 64-bit
  909. operating system running on it).  That was because `g77' was known to
  910. not work properly on such configurations.
  911.  
  912.    As of version 0.5.20, `g77' is believed to work well enough on such
  913. systems.  So, the warning is no longer needed or provided.
  914.  
  915.    However, support for 64-bit systems, especially in areas such as
  916. cross-compilation and handling of intrinsics, is still incomplete.  The
  917. symptoms are believed to be compile-time diagnostics rather than the
  918. generation of bad code.  It is hoped that version 0.6 will completely
  919. support 64-bit systems.
  920.  
  921. 
  922. File: g77.info,  Node: Quick Start,  Next: Complete Installation,  Prev: Settings,  Up: Installation
  923.  
  924. Quick Start
  925. ===========
  926.  
  927.    For users of the GCC-2.95 version of `g77', this information is
  928. superceded by the GCC installation instructions.
  929.  
  930. 
  931. File: g77.info,  Node: Complete Installation,  Next: Distributing Binaries,  Prev: Quick Start,  Up: Installation
  932.  
  933. Complete Installation
  934. =====================
  935.  
  936.    For users of the GCC-2.95 version of `g77', this information is
  937. superceded by the GCC installation instructions.
  938.  
  939. 
  940. File: g77.info,  Node: Distributing Binaries,  Prev: Complete Installation,  Up: Installation
  941.  
  942. Distributing Binaries
  943. =====================
  944.  
  945.    For users of the GCC-2.95 version of `g77', this information is
  946. superceded by the GCC installation instructions.
  947.  
  948. 
  949. File: g77.info,  Node: Debugging and Interfacing,  Next: Collected Fortran Wisdom,  Prev: Installation,  Up: Top
  950.  
  951. Debugging and Interfacing
  952. *************************
  953.  
  954.    GNU Fortran currently generates code that is object-compatible with
  955. the `f2c' converter.  Also, it avoids limitations in the current GBE,
  956. such as the inability to generate a procedure with multiple entry
  957. points, by generating code that is structured differently (in terms of
  958. procedure names, scopes, arguments, and so on) than might be expected.
  959.  
  960.    As a result, writing code in other languages that calls on, is
  961. called by, or shares in-memory data with `g77'-compiled code generally
  962. requires some understanding of the way `g77' compiles code for various
  963. constructs.
  964.  
  965.    Similarly, using a debugger to debug `g77'-compiled code, even if
  966. that debugger supports native Fortran debugging, generally requires
  967. this sort of information.
  968.  
  969.    This section describes some of the basic information on how `g77'
  970. compiles code for constructs involving interfaces to other languages
  971. and to debuggers.
  972.  
  973.    *Caution:* Much or all of this information pertains to only the
  974. current release of `g77', sometimes even to using certain compiler
  975. options with `g77' (such as `-fno-f2c').  Do not write code that
  976. depends on this information without clearly marking said code as
  977. nonportable and subject to review for every new release of `g77'.  This
  978. information is provided primarily to make debugging of code generated
  979. by this particular release of `g77' easier for the user, and partly to
  980. make writing (generally nonportable) interface code easier.  Both of
  981. these activities require tracking changes in new version of `g77' as
  982. they are installed, because new versions can change the behaviors
  983. described in this section.
  984.  
  985. * Menu:
  986.  
  987. * Main Program Unit::  How `g77' compiles a main program unit.
  988. * Procedures::         How `g77' constructs parameter lists
  989.                        for procedures.
  990. * Functions::          Functions returning floating-point or character data.
  991. * Names::              Naming of user-defined variables, procedures, etc.
  992. * Common Blocks::      Accessing common variables while debugging.
  993. * Local Equivalence Areas::  Accessing `EQUIVALENCE' while debugging.
  994. * Complex Variables::  How `g77' performs complex arithmetic.
  995. * Arrays::             Dealing with (possibly multi-dimensional) arrays.
  996. * Adjustable Arrays::  Special consideration for adjustable arrays.
  997. * Alternate Entry Points::  How `g77' implements alternate `ENTRY'.
  998. * Alternate Returns::  How `g77' handles alternate returns.
  999. * Assigned Statement Labels::  How `g77' handles `ASSIGN'.
  1000. * Run-time Library Errors::  Meanings of some `IOSTAT=' values.
  1001.  
  1002. 
  1003. File: g77.info,  Node: Main Program Unit,  Next: Procedures,  Up: Debugging and Interfacing
  1004.  
  1005. Main Program Unit (PROGRAM)
  1006. ===========================
  1007.  
  1008.    When `g77' compiles a main program unit, it gives it the public
  1009. procedure name `MAIN__'.  The `libg2c' library has the actual `main()'
  1010. procedure as is typical of C-based environments, and it is this
  1011. procedure that performs some initial start-up activity and then calls
  1012. `MAIN__'.
  1013.  
  1014.    Generally, `g77' and `libg2c' are designed so that you need not
  1015. include a main program unit written in Fortran in your program--it can
  1016. be written in C or some other language.  Especially for I/O handling,
  1017. this is the case, although `g77' version 0.5.16 includes a bug fix for
  1018. `libg2c' that solved a problem with using the `OPEN' statement as the
  1019. first Fortran I/O activity in a program without a Fortran main program
  1020. unit.
  1021.  
  1022.    However, if you don't intend to use `g77' (or `f2c') to compile your
  1023. main program unit--that is, if you intend to compile a `main()'
  1024. procedure using some other language--you should carefully examine the
  1025. code for `main()' in `libg2c', found in the source file
  1026. `egcs/libf2c/libF77/main.c', to see what kinds of things might need to
  1027. be done by your `main()' in order to provide the Fortran environment
  1028. your Fortran code is expecting.
  1029.  
  1030.    For example, `libg2c''s `main()' sets up the information used by the
  1031. `IARGC' and `GETARG' intrinsics.  Bypassing `libg2c''s `main()' without
  1032. providing a substitute for this activity would mean that invoking
  1033. `IARGC' and `GETARG' would produce undefined results.
  1034.  
  1035.    When debugging, one implication of the fact that `main()', which is
  1036. the place where the debugged program "starts" from the debugger's point
  1037. of view, is in `libg2c' is that you won't be starting your Fortran
  1038. program at a point you recognize as your Fortran code.
  1039.  
  1040.    The standard way to get around this problem is to set a break point
  1041. (a one-time, or temporary, break point will do) at the entrance to
  1042. `MAIN__', and then run the program.  A convenient way to do so is to
  1043. add the `gdb' command
  1044.  
  1045.      tbreak MAIN__
  1046.  
  1047. to the file `.gdbinit' in the directory in which you're debugging
  1048. (using `gdb').
  1049.  
  1050.    After doing this, the debugger will see the current execution point
  1051. of the program as at the beginning of the main program unit of your
  1052. program.
  1053.  
  1054.    Of course, if you really want to set a break point at some other
  1055. place in your program and just start the program running, without first
  1056. breaking at `MAIN__', that should work fine.
  1057.  
  1058. 
  1059. File: g77.info,  Node: Procedures,  Next: Functions,  Prev: Main Program Unit,  Up: Debugging and Interfacing
  1060.  
  1061. Procedures (SUBROUTINE and FUNCTION)
  1062. ====================================
  1063.  
  1064.    Currently, `g77' passes arguments via reference--specifically, by
  1065. passing a pointer to the location in memory of a variable, array, array
  1066. element, a temporary location that holds the result of evaluating an
  1067. expression, or a temporary or permanent location that holds the value
  1068. of a constant.
  1069.  
  1070.    Procedures that accept `CHARACTER' arguments are implemented by
  1071. `g77' so that each `CHARACTER' argument has two actual arguments.
  1072.  
  1073.    The first argument occupies the expected position in the argument
  1074. list and has the user-specified name.  This argument is a pointer to an
  1075. array of characters, passed by the caller.
  1076.  
  1077.    The second argument is appended to the end of the user-specified
  1078. calling sequence and is named `__g77_length_X', where X is the
  1079. user-specified name.  This argument is of the C type `ftnlen' (see
  1080. `egcs/libf2c/g2c.h.in' for information on that type) and is the number
  1081. of characters the caller has allocated in the array pointed to by the
  1082. first argument.
  1083.  
  1084.    A procedure will ignore the length argument if `X' is not declared
  1085. `CHARACTER*(*)', because for other declarations, it knows the length.
  1086. Not all callers necessarily "know" this, however, which is why they all
  1087. pass the extra argument.
  1088.  
  1089.    The contents of the `CHARACTER' argument are specified by the
  1090. address passed in the first argument (named after it).  The procedure
  1091. can read or write these contents as appropriate.
  1092.  
  1093.    When more than one `CHARACTER' argument is present in the argument
  1094. list, the length arguments are appended in the order the original
  1095. arguments appear.  So `CALL FOO('HI','THERE')' is implemented in C as
  1096. `foo("hi","there",2,5);', ignoring the fact that `g77' does not provide
  1097. the trailing null bytes on the constant strings (`f2c' does provide
  1098. them, but they are unnecessary in a Fortran environment, and you should
  1099. not expect them to be there).
  1100.  
  1101.    Note that the above information applies to `CHARACTER' variables and
  1102. arrays *only*.  It does *not* apply to external `CHARACTER' functions
  1103. or to intrinsic `CHARACTER' functions.  That is, no second length
  1104. argument is passed to `FOO' in this case:
  1105.  
  1106.      CHARACTER X
  1107.      EXTERNAL X
  1108.      CALL FOO(X)
  1109.  
  1110. Nor does `FOO' expect such an argument in this case:
  1111.  
  1112.      SUBROUTINE FOO(X)
  1113.      CHARACTER X
  1114.      EXTERNAL X
  1115.  
  1116.    Because of this implementation detail, if a program has a bug such
  1117. that there is disagreement as to whether an argument is a procedure,
  1118. and the type of the argument is `CHARACTER', subtle symptoms might
  1119. appear.
  1120.  
  1121. 
  1122. File: g77.info,  Node: Functions,  Next: Names,  Prev: Procedures,  Up: Debugging and Interfacing
  1123.  
  1124. Functions (FUNCTION and RETURN)
  1125. ===============================
  1126.  
  1127.    `g77' handles in a special way functions that return the following
  1128. types:
  1129.  
  1130.    * `CHARACTER'
  1131.  
  1132.    * `COMPLEX'
  1133.  
  1134.    * `REAL(KIND=1)'
  1135.  
  1136.    For `CHARACTER', `g77' implements a subroutine (a C function
  1137. returning `void') with two arguments prepended: `__g77_result', which
  1138. the caller passes as a pointer to a `char' array expected to hold the
  1139. return value, and `__g77_length', which the caller passes as an
  1140. `ftnlen' value specifying the length of the return value as declared in
  1141. the calling program.  For `CHARACTER*(*)', the called function uses
  1142. `__g77_length' to determine the size of the array that `__g77_result'
  1143. points to; otherwise, it ignores that argument.
  1144.  
  1145.    For `COMPLEX', when `-ff2c' is in force, `g77' implements a
  1146. subroutine with one argument prepended: `__g77_result', which the
  1147. caller passes as a pointer to a variable of the type of the function.
  1148. The called function writes the return value into this variable instead
  1149. of returning it as a function value.  When `-fno-f2c' is in force,
  1150. `g77' implements a `COMPLEX' function as `gcc''s `__complex__ float' or
  1151. `__complex__ double' function (or an emulation thereof, when
  1152. `-femulate-complex' is in effect), returning the result of the function
  1153. in the same way as `gcc' would.
  1154.  
  1155.    For `REAL(KIND=1)', when `-ff2c' is in force, `g77' implements a
  1156. function that actually returns `REAL(KIND=2)' (typically C's `double'
  1157. type).  When `-fno-f2c' is in force, `REAL(KIND=1)' functions return
  1158. `float'.
  1159.  
  1160. 
  1161. File: g77.info,  Node: Names,  Next: Common Blocks,  Prev: Functions,  Up: Debugging and Interfacing
  1162.  
  1163. Names
  1164. =====
  1165.  
  1166.    Fortran permits each implementation to decide how to represent names
  1167. as far as how they're seen in other contexts, such as debuggers and
  1168. when interfacing to other languages, and especially as far as how
  1169. casing is handled.
  1170.  
  1171.    External names--names of entities that are public, or "accessible",
  1172. to all modules in a program--normally have an underscore (`_') appended
  1173. by `g77', to generate code that is compatible with `f2c'.  External
  1174. names include names of Fortran things like common blocks, external
  1175. procedures (subroutines and functions, but not including statement
  1176. functions, which are internal procedures), and entry point names.
  1177.  
  1178.    However, use of the `-fno-underscoring' option disables this kind of
  1179. transformation of external names (though inhibiting the transformation
  1180. certainly improves the chances of colliding with incompatible externals
  1181. written in other languages--but that might be intentional.
  1182.  
  1183.    When `-funderscoring' is in force, any name (external or local) that
  1184. already has at least one underscore in it is implemented by `g77' by
  1185. appending two underscores.  (This second underscore can be disabled via
  1186. the `-fno-second-underscore' option.)  External names are changed this
  1187. way for `f2c' compatibility.  Local names are changed this way to avoid
  1188. collisions with external names that are different in the source
  1189. code--`f2c' does the same thing, but there's no compatibility issue
  1190. there except for user expectations while debugging.
  1191.  
  1192.    For example:
  1193.  
  1194.      Max_Cost = 0
  1195.  
  1196. Here, a user would, in the debugger, refer to this variable using the
  1197. name `max_cost__' (or `MAX_COST__' or `Max_Cost__', as described below).
  1198. (We hope to improve `g77' in this regard in the future--don't write
  1199. scripts depending on this behavior!  Also, consider experimenting with
  1200. the `-fno-underscoring' option to try out debugging without having to
  1201. massage names by hand like this.)
  1202.  
  1203.    `g77' provides a number of command-line options that allow the user
  1204. to control how case mapping is handled for source files.  The default
  1205. is the traditional UNIX model for Fortran compilers--names are mapped
  1206. to lower case.  Other command-line options can be specified to map
  1207. names to upper case, or to leave them exactly as written in the source
  1208. file.
  1209.  
  1210.    For example:
  1211.  
  1212.      Foo = 9.436
  1213.  
  1214. Here, it is normally the case that the variable assigned will be named
  1215. `foo'.  This would be the name to enter when using a debugger to access
  1216. the variable.
  1217.  
  1218.    However, depending on the command-line options specified, the name
  1219. implemented by `g77' might instead be `FOO' or even `Foo', thus
  1220. affecting how debugging is done.
  1221.  
  1222.    Also:
  1223.  
  1224.      Call Foo
  1225.  
  1226. This would normally call a procedure that, if it were in a separate C
  1227. program, be defined starting with the line:
  1228.  
  1229.      void foo_()
  1230.  
  1231. However, `g77' command-line options could be used to change the casing
  1232. of names, resulting in the name `FOO_' or `Foo_' being given to the
  1233. procedure instead of `foo_', and the `-fno-underscoring' option could
  1234. be used to inhibit the appending of the underscore to the name.
  1235.  
  1236.